Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 3 - QuickDraw 3D Objects

Using QuickDraw 3D Objects

This section describes the most basic ways of using QuickDraw 3D objects. In particular, it provides source code examples that show how you can

• determine the type of a QuickDraw 3D object
• define a simple object metahandler to support a custom attribute type

Determining the Type of a QuickDraw 3D Object

Every class in the QuickDraw 3D class hierarchy has a unique type identifier associated with it. For example, the triangle class has the type identifier kQ3GeometryTypeTriangle. For objects you create, of course, you'll generally know the type of the object. In some instances, however, you might need to determine an object's type, so that you know what methods apply to the object. For example, when you read an object from a file, you don't usually know what kind of object you've read.

The QuickDraw 3D class hierarchy supports _GetType methods at all levels of the hierarchy. At the root level, the function Q3Object_GetType returns a constant of the form kQ3ObjectTypeSubClass, where SubClass is replaced by the appropriate subclass identifier.

For example, suppose you've read an object (which happens to be a triangle) from a file and you want to determine what kind of object it is. You can call the Q3Object_GetType function, which returns the value kQ3ObjectTypeShared. To determine what kind of shared object it is, you can call the Q3Shared_GetType function, which in this case returns the value kQ3SharedTypeShape. To determine what kind of shape object it is, you can call the Q3Shape_GetType function, which in this case returns the value kQ3ShapeTypeGeometry. Finally, you can determine what kind of geometric object it is by calling Q3Geometry_GetType; in this case, Q3Geometry_GetType returns the value kQ3GeometryTypeTriangle.

Instead of descending the class hierarchy in this way, you can also determine the leaf type of an object by calling the Q3Object_GetLeafType function. (An object's leaf type is the identifier of a leaf class.) In this example, calling Q3Object_GetLeafType returns the constant kQ3GeometryTypeTriangle.

You can also use the Q3Object_IsType function to determine if an object is of a particular type.

Defining an Object Metahandler

QuickDraw 3D allows you to define object types in addition to those it provides itself. For example, you can add a custom type of attribute so that
you can attach custom data to objects or parts of objects in a model.

To define a custom object type, you first define the structure of the data associated with your custom object type. Then you must write an object metahandler to define a set of object-handling methods. QuickDraw 3D calls those methods at certain times to handle operations on your custom object. For example, when someone calls Q3Object_Submit to draw an object of your custom type, QuickDraw 3D must call your object's drawing method.

Your object metahandler is an application-defined function that returns the addresses of the methods associated with the custom object type. QuickDraw 3D supports a large number of object methods. All custom objects should support this method:

kQ3MethodTypeObjectUnregister

Note

See "Application-Defined Routines," beginning on page 3-28 for more information on defining custom object methods.

Custom objects that are to be read from and written to files should support these I/O methods:

kQ3MethodTypeObjectTraverse
kQ3MethodTypeObjectWrite
kQ3MethodTypeObjectReadData

Note

See the chapter "File Objects" for more information on defining custom I/O methods.

Custom attribute types should support these methods:

kQ3MethodTypeAttributeCopyInherit
kQ3MethodTypeAttributeInherit

Note

See the chapter "Attribute Objects" for more information on defining custom attribute types.

Custom element types should support these methods:

kQ3MethodTypeElementCopyAdd
kQ3MethodTypeElementCopyReplace
kQ3MethodTypeElementCopyGet
kQ3MethodTypeElementCopyDuplicate
kQ3MethodTypeElementDelete

Note

See "Defining Custom Elements," beginning on page 3-17 for more information on defining custom element types.

Listing 3-1 defines a simple attribute metahandler.

Listing 3-1 Reporting custom object methods

TQ3FunctionPointer MyObjectMetaHandler (TQ3MethodType methodType)
{
   switch (methodType) {
      case kQ3MethodTypeObjectUnregister:
         return (TQ3FunctionPointer) MyObject_Unregister;
      default:
         return (NULL);
   }
}

As you can see, the MyObjectMetaHandler metahandler simply returns the appropriate function address, or NULL if the metahandler does not implement a particular method type.

Defining Custom Elements

You can define custom element types if you'd like to support types of attributes other than those provided by QuickDraw 3D. You define custom attributes as custom elements because attributes are almost always contained in an attribute set, of type TQ3AttributeSet. More generally, you can define custom element types that can be included in a set of type TQ3SetObject.

To define a custom element type, you need to define and register (using your element metahandler) custom element methods. Currently, QuickDraw 3D supports five element methods, corresponding to these constants:

kQ3MethodTypeElementCopyAdd
kQ3MethodTypeElementCopyReplace
kQ3MethodTypeElementCopyGet
kQ3MethodTypeElementCopyDuplicate
kQ3MethodTypeElementDelete

The four copy methods are called to add a new element of your custom type
to a set, to replace an existing element of your custom type, to get the
data associated with an element of your custom type, and to duplicate the data associated with an element of your custom type. Note that the data you maintain internally for a custom element type can differ from the data you return to an application when it calls Q3Set_Get or Q3AttributeSet_Get.